home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / tiff / README.lib < prev    next >
Text File  |  1995-06-21  |  13KB  |  252 lines
  1. $Header: /usr/people/sam/tiff/libtiff/RCS/README,v 1.19 1994/07/26 16:48:07 sam Exp $
  2. #
  3. # Tag Image File Format Library
  4. #
  5. # Copyright (c) 1988, 1989, 1990, 1991, 1992, 1993, 1994 Sam Leffler
  6. # Copyright (c) 1991, 1992, 1993, 1994 Silicon Graphics, Inc.
  7. # 
  8. # Permission to use, copy, modify, distribute, and sell this software and 
  9. # its documentation for any purpose is hereby granted without fee, provided
  10. # that (i) the above copyright notices and this permission notice appear in
  11. # all copies of the software and related documentation, and (ii) the names of
  12. # Sam Leffler and Silicon Graphics may not be used in any advertising or
  13. # publicity relating to the software without the specific, prior written
  14. # permission of Sam Leffler and Silicon Graphics.
  15. # 
  16. # THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
  17. # EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
  18. # WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
  19. # 
  20. # IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  21. # ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  22. # OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  23. # WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
  24. # LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
  25. # OF THIS SOFTWARE.
  26. #
  27.  
  28. Configuration Comments:
  29. ----------------------
  30. Aside from the compression algorithm support, there are
  31. configuration-related defines that you can override in the Makefile
  32. or in the default configuration file tiffconf.h:
  33.  
  34. COLORIMETRY_SUPPORT
  35.         if this is defined, support for the colorimetry
  36.         tags will be compiled in.
  37. JPEG_SUPPORT    if this is defined, support for the JPEG-related
  38.         tags will be compiled in.  Note that at the present
  39.         time the JPEG compression support is not included.
  40. YCBCR_SUPPORT    if this is defined, support for the YCbCr-related
  41.         tags will be compiled in.  Note that you'll want
  42.         YCBCR support for JPEG compression+decompression.
  43. CMYK_SUPPORT    if this is defined, support for the CMYK-related
  44.         tags will be compiled in.
  45. MMAP_SUPPORT    if this is set, and OS support exists for memory
  46.         mapping files, then the library will try to map
  47.         a file if it is opened for reading.  If mmap does
  48.         not exist on your system, or the mmap call fails
  49.         on the file, then the normal read system calls are
  50.         used.  It is not clear how useful this facility is.
  51.  
  52. By default tiffconf.h defines COLORIMETRY_SUPPORT, JPEG_SUPPORT,
  53. YCBCR_SUPPORT, CMYK_SUPPORT.  MMAP_SUPPORT is not defined.
  54.  
  55. General Portability Comments:
  56. ----------------------------
  57. I run this code on SGI machines (big-endian, MIPS CPU, 32-bit ints,
  58. IEEE floating point).  Makefiles exist for other platforms that the
  59. code runs on -- this work has mostly been done by other people.
  60. The code runs on Macintosh and PC-based systems, although I don't
  61. know all the particulars.
  62.  
  63. In general, I promise only that the code runs on SGI machines.
  64. I will, however, gladly take back fixes to make it work on other
  65. systems -- when the changes are reasonable unobtrusive.
  66.  
  67. The software is written to assume an ANSI C compilation environment.
  68. If your compiler does not support ANSI function prototypes, const,
  69. and <stdarg.h> then you will have to make modifications to the
  70. software.  In the past I have tried to support compilers w/o const
  71. and systems w/o <stdarg.h>, but I am NO LONGER INTERESTED in these
  72. antiquated environments.  With the general availability of gcc, I
  73. see no reason to incorporate modifications to the software for these
  74. purposes.
  75.  
  76. I've tried to isolate as many of the OS-dependencies as possible in
  77. two files: tiffcomp.h and tif_<os>.c.  The latter file contains
  78. OS-specific routines to do I/O and I/O-related operations.  The
  79. UNIX (tif_unix.c), Macintosh (tif_apple.c), and VMS (tif_vms.c)
  80. code has had the most use; the MS/DOS support (tif_msdos.c) assumes
  81. some level of UNIX system call emulation (i.e. open, read, write,
  82. fstat, malloc, free).
  83.  
  84. Machine dependencies such as byte order are determined on the
  85. fly and do not need to be specified.
  86.  
  87. Two general portability-related defines are:
  88.  
  89. BSDTYPES    Define this if your system does NOT define the
  90.         usual BSD typedefs: u_char, u_short, u_int, u_longs.
  91. HAVE_IEEEFP    Define this as 0 or 1 according to the floating point
  92.         format suported by the machine.  If your machine does
  93.         not support IEEE floating point then you will need to
  94.         add support to tif_machdep.c to convert between the
  95.         native format and IEEE format.
  96.  
  97. Note that tiffcomp.h defines HAVE_IEEEFP to be 1 (BSDTYPES is not defined).
  98.  
  99. Types and Portability:
  100. ---------------------
  101. The software makes extensive use of typedefs to promote portability.
  102. Two sets of typedefs are used, one for communication with clients
  103. of the library and one for internal data structures and parsing of the
  104. TIFF format.  There are interactions between these two to be careful
  105. of, but for the most part you should be able to deal with portability
  106. purely by fiddling with the following machine-dependent typedefs:
  107.  
  108. uint16        16-bit unsigned integer        tiff.h
  109. int16        16-bit signed integer        tiff.h
  110. uint32        32-bit unsigned integer        tiff.h
  111. int32        32-bit signed integer        tiff.h
  112. dblparam_t    promoted type for floats    tiffcomp.h
  113.  
  114. (to clarify dblparam_t, it is the type that float parameters are
  115. promoted to when passed by value in a function call.)
  116.  
  117. The following typedefs are used throughout the library and interfaces
  118. to refer to certain objects whose size is dependent on the TIFF image
  119. structure:
  120.  
  121. typedef    unsigned int ttag_t;    directory tag
  122. typedef    uint16 tdir_t;        directory index
  123. typedef    uint16 tsample_t;    sample number
  124. typedef    uint32 tstrip_t;    strip number
  125. typedef uint32 ttile_t;        tile number
  126. typedef    int32 tsize_t;        i/o size in bytes
  127. typedef    void* tdata_t;        image data ref
  128. typedef    void* thandle_t;    client data handle
  129. typedef    int32 toff_t;        file offset (should be off_t)
  130. typedef    unsigned char* tidata_t;internal image data
  131.  
  132. Note that tstrip_t, ttile_t, and tsize_t are constrained to be
  133. no more than 32-bit quantities by 32-bit fields they are stored
  134. in in the TIFF image.  Likewise tsample_t is limited by the 16-bit
  135. field used to store the SamplesPerPixel tag.  tdir_t constrains
  136. the maximum number of IFDs that may appear in an image and may
  137. be an arbitrary size (w/o penalty).  ttag_t must be either int,
  138. unsigned int, pointer, or double because the library uses a varargs
  139. interface and ANSI restricts the type of the parameter before an
  140. ellipsis to be a promoted type.  toff_t is defined as int32 because
  141. TIFF file offsets are (unsigned) 32-bit quantities.  A signed
  142. value is used because some interfaces return -1 on error (sigh).
  143. Finally, note that tidata_t is used internally to the library to
  144. manipulate internal data.  User-specified data references are
  145. passed as opaque handles and only cast at the lowest layers where
  146. their type is presumed.
  147.  
  148. General Comments:
  149. ----------------
  150. The library is designed to hide as much of the details of TIFF as
  151. possible.  In particular, TIFF directories are read in their entirety
  152. into an internal format.  Only the tags known by the library are
  153. available to a user and certain tag data may be maintained that a user
  154. doesn't care about (e.g. transfer function tables).
  155.  
  156. To add support for a new directory tag the following mods are needed:
  157.  
  158. 1. Define the tag in tiff.h.
  159. 2. Add a field to the directory structure in tiffiop.h and define a
  160.    FIELD_* bit.
  161. 3. Add an entry in the FieldInfo array defined at the top of tiff_dirinfo.c.
  162. 4. Add entries in TIFFSetField1() and TIFFGetField1() for the new tag.
  163. 5. (optional) If the value associated with the tag is not a scalar value
  164.    (e.g. the array for TransferFunction), then add the appropriate
  165.    code to TIFFReadDirectory() and TIFFWriteDirectory().  You're best
  166.    off finding a similar tag and cribbing code.
  167. 6. Add support to TIFFPrintDirectory() in tiff_print.c to print the
  168.    tag's value.
  169.  
  170. If you want to maintain portability, beware of making assumptions
  171. about data types.  Use the typedefs (uint16, etc. when dealing with
  172. data on disk and t*_t when stuff is in memory) and be careful about
  173. passing items through printf or similar vararg interfaces.
  174.  
  175. To add support for a compression algorithm:
  176.  
  177. 1. Define the tag value in tiff.h.
  178. 2. Edit the file tiff_compress.c to add an entry to the
  179.    CompressionSchemes[] array.
  180. 3. Create a file with the compression scheme code, by convention files
  181.    are named tif_*.c (except perhaps on some systems where the tif_ prefix
  182.    pushes some filenames over 14 chars.
  183. 4. Edit the Makefiles to include the new source file.
  184.  
  185. A compression scheme, say foo, can have up to 10 entry points:
  186.  
  187. TIFFfoo(tif)        /* initialize scheme and setup entry points in tif */
  188. fooPreDecode(tif)    /* called once per strip, after data is read,
  189.                but before the first row in a strip is decoded */
  190. fooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */
  191.     fooDecodeRow(...)    /* called to decode a single scanline */
  192.     fooDecodeStrip(...)    /* called to decode an entire strip */
  193.     fooDecodeTile(...)    /* called to decode an entire tile */
  194. fooPreEncode(tif)    /* called once per strip/tile, before the first row in
  195.                a strip is encoded */
  196. fooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */
  197.     fooEncodeRow(...)    /* called to decode a single scanline */
  198.     fooEncodeStrip(...)    /* called to decode an entire strip */
  199.     fooEncodeTile(...)    /* called to decode an entire tile */
  200. fooPostEncode(tif)    /* called once per strip/tile, just before data is written */
  201. fooSeek(tif, row)    /* seek forwards row scanlines from the beginning
  202.                of a strip (row will always be >0 and <rows/strip */
  203. fooCleanup(tif)        /* called when compression scheme is replaced by user */
  204.  
  205. Note that the encoding and decoding variants are only needed when
  206. a compression algorithm is dependent on the structure of the data.
  207. For example, Group 3 2D encoding and decoding maintains a reference
  208. scanline.  The sample parameter identifies which sample is to be
  209. encoded or decoded if the image is organized with PlanarConfig=2
  210. (separate planes).  This is important for algorithms such as JPEG.
  211. If PlanarConfig=1 (interleaved), then sample will always be 0.
  212.  
  213. The library handles most I/O buffering.  There are two data buffers
  214. when decoding data: a raw data buffer that holds all the data in a
  215. strip, and a user-supplied scanline buffer that compression schemes
  216. place decoded data into.  When encoding data the data in the
  217. user-supplied scanline buffer is encoded into the raw data buffer (from
  218. where it's written).  Decoding routines should never have to explicitly
  219. read data -- a full strip/tile's worth of raw data is read and scanlines
  220. never cross strip boundaries.  Encoding routines must be cognizant of
  221. the raw data buffer size and call TIFFFlushData1() when necessary.
  222. Note that any pending data is automatically flushed when a new strip/tile is
  223. started, so there's no need do that in the tif_postencode routine (if
  224. one exists).  Bit order is automatically handled by the library when
  225. a raw strip or tile is filled.  If the decoded samples are interpreted
  226. by the decoding routine before they are passed back to the user, then
  227. the decoding logic must handle byte-swapping by overriding the tif_postdecode
  228. routine (set it to TIFFNoPostDecode) and doing the required work
  229. internally.  For an example of doing this look at the horizontal
  230. differencing code in the LZW decoding routines.
  231.  
  232. The variables tif_rawcc, tif_rawdata, and tif_rawcp in a TIFF structure
  233. are associated with the raw data buffer.  tif_rawcc must be non-zero
  234. for the library to automatically flush data.  The variable
  235. tif_scanlinesize is the size a user's scanline buffer should be.  The
  236. variable tif_tilesize is the size of a tile for tiled images.  This
  237. should not normally be used by compression routines, except where it
  238. relates to the compression algorithm.  That is, the cc parameter to the
  239. tif_decode* and tif_encode* routines should be used in terminating
  240. decompression/compression.  This ensures these routines can be used,
  241. for example, to decode/encode entire strips of data.
  242.  
  243. In general, if you have a new compression algorithm to add, work from
  244. the code for an existing routine.  In particular, tiff_dumpmode.c has
  245. the trivial code for the "nil" compression scheme, tiff_packbits.c is a
  246. simple byte-oriented scheme that has to watch out for buffer
  247. boundaries, and tiff_lzw.c has the LZW scheme that has the most
  248. complexity -- it tracks the buffer boundary at a bit level.
  249.  
  250. Of course, using a private compression scheme (or private tags) limits
  251. the portability of your TIFF files.
  252.